<HTML>
<HEAD>
<TITLE> DAS Required Reading </TITLE>
</HEAD>

<BODY style="color: rgb(0, 0, 0); background-color: rgb(255, 255, 255);">

<A NAME="top"></A>

<TABLE STYLE="text-align: left; margin-left: auto; margin-right: auto; width: 800px;" BORDER="0" CELLPADDING="5" CELLSPACING="2">
<TBODY>
<TR>
  <TD STYLE="background-color: rgb(153, 153, 153); vertical-align: middle; text-align: center;">
  <DIV ALIGN="right">
    <SMALL><SMALL><A HREF="index.html">Index Page</A></SMALL></SMALL>
  </DIV>
  <B>DAS Required Reading</B> </TD>
</TR>
<TR>
  <TD STYLE="vertical-align: top;">

<H2> Table of Contents
</H2>

<PRE>
   <A HREF="#DAS Required Reading">DAS Required Reading</A>
      <A HREF="#Abstract">Abstract</A>
      <A HREF="#Notes for CSPICE users">Notes for CSPICE users</A>
      <A HREF="#Intended audience">Intended audience</A>
      <A HREF="#Related Documents">Related Documents</A>
      <A HREF="#Introduction">Introduction</A>
   <A HREF="#Using the DAS Subsystem">Using the DAS Subsystem</A>
      <A HREF="#Prerequisites">Prerequisites</A>
         <A HREF="#Logical Addresses">Logical Addresses</A>
         <A HREF="#Read and Write Access">Read and Write Access</A>
         <A HREF="#File Handles">File Handles</A>
         <A HREF="#The DAS Comment Area">The DAS Comment Area</A>
         <A HREF="#Internal File Names">Internal File Names</A>
         <A HREF="#Binary and Transfer DAS files">Binary and Transfer DAS files</A>
         <A HREF="#Buffering">Buffering</A>
         <A HREF="#Using Multiple DAS Files Simultaneously">Using Multiple DAS Files Simultaneously</A>
         <A HREF="#DAS vs DAF">DAS vs DAF</A>
      <A HREF="#Using DAS Subroutines">Using DAS Subroutines</A>
         <A HREF="#Creating a New DAS File">Creating a New DAS File</A>
         <A HREF="#Writing DAS Files">Writing DAS Files</A>
         <A HREF="#Writing to an Existing DAS file">Writing to an Existing DAS file</A>
         <A HREF="#Reading DAS Files">Reading DAS Files</A>
         <A HREF="#Converting Between Binary and Transfer Format">Converting Between Binary and Transfer Format</A>
         <A HREF="#Annotating DAS Files">Annotating DAS Files</A>
         <A HREF="#Mapping Between Handles, File Names, and Units">Mapping Between Handles, File Names, and Units</A>
         <A HREF="#Obtaining a DAS File Summary">Obtaining a DAS File Summary</A>
         <A HREF="#Using Scratch DAS Files">Using Scratch DAS Files</A>
   <A HREF="#DAS Architecture">DAS Architecture</A>
         <A HREF="#Overview of DAS Architecture">Overview of DAS Architecture</A>
         <A HREF="#The File Record">The File Record</A>
         <A HREF="#Reserved Records">Reserved Records</A>
         <A HREF="#Comment Records">Comment Records</A>
         <A HREF="#Directory Records">Directory Records</A>
         <A HREF="#Data Records">Data Records</A>
   <A HREF="#DAS Routines">DAS Routines</A>
         <A HREF="#Summary of Mnemonics">Summary of Mnemonics</A>
         <A HREF="#Summary of Calling Sequences">Summary of Calling Sequences</A>
   <A HREF="#Examples">Examples</A>
         <A HREF="#Storing a Symbol Table in a DAS File">Storing a Symbol Table in a DAS File</A>

</PRE>

<HR SIZE=3 NOSHADE>

<BR><BR>
<A NAME="DAS Required Reading"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H1> DAS Required Reading
</H1><HR SIZE=3 NOSHADE><P><BR><BR><BR>
   Last revised on 2009 APR 01 by B. V. Semenov.
<P>
 
<BR><BR>
<A NAME="Abstract"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Abstract
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   Direct Access Segregated File, DAS, is an architecture for files that
   stores arrays of integer, double precision, and character data. The
   SPICE EK and DBK files use the DAS architecture and associated software.
<P>
 
<BR><BR>
<A NAME="Notes for CSPICE users"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Notes for CSPICE users
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   This document currently discusses only the Fortran version of the SPICE
   DAS subsystem. The CSPICE version provides identical functionality.
<P>
 
   At this time, the CSPICE DAS subsystem consists solely of modules
   translated from Fortran via f2c; there are no DAS interface wrappers.
<P>
 
   For a given platform, DAS files used by the Fortran and C SPICE Toolkits
   are identical.
<P>
 
<BR><BR>
<A NAME="Intended audience"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Intended audience
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   This document is intended primarily for sophisticated SPICELIB users who
   wish to create their own DAS-based file formats. Users of SPICE kernels
   based on the DAS format can find documentation of the interface to those
   kernels in the Required Reading for the appropriate kernel type.
<P>
 
<BR><BR>
<A NAME="Related Documents"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Related Documents
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   The following documents pertinent to DAS usage are included in the
   CSPICE Toolkit:
<P>
 
<UL>
<TT>1.</TT> Convert User's Guide (<a href="../ug/convert.html">convert.ug</a>)
<BR><BR></UL>
<UL>
<TT>2.</TT> COMMNT User's Guide (<a href="../ug/commnt.html">commnt.ug</a>)
<BR><BR></UL>
<BR><BR>
<A NAME="Introduction"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Introduction
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   The SPICELIB ``DAS'' subsystem consists of a Fortran 77 direct access
   file architecture and a set of subroutines that make it convenient to
   create, read, annotate, and transport files having this architecture.
<P>
 
   The purpose of the DAS subsystem is to provide SPICELIB users with a
   simple way to create and efficiently use their own portable, high-level,
   binary, direct access file formats. The DAS architecture is meant to
   serve as a foundation for these high-level formats, providing services
   and capabilities required by all of them.
<P>
 
   The principal advantage of building a new file format based on DAS is
   that most of the new access routines---the new code needed to support
   reading, writing, and porting files having the new format---can be built
   out of DAS routines. Thus a great deal of the design, coding,
   documentation and testing that accompanies the development of new access
   routines is automatically eliminated. In addition, because files
   conforming to the new format are also DAS files, they inherit the
   features common to all DAS files:
<P>
 
<UL>
<TT>--</TT> Direct file access
<BR><BR></UL>
<UL>
<TT>--</TT> Simple interface---data is referenced by ``logical address''
<BR><BR></UL>
<UL>
<TT>--</TT> Support for character, double precision, and integer data types
<BR><BR></UL>
<UL>
<TT>--</TT> Built-in portability
<BR><BR></UL>
<UL>
<TT>--</TT> Built-in file annotation capability
<BR><BR></UL>
<UL>
<TT>--</TT> System-independent I/O buffering
<BR><BR></UL>
   The acronym ``DAS'' stands for ``direct access, segregated.'' The DAS
   subsystem enables application programs to view data in a DAS file as
   though the data were segregated into three separate one-dimensional
   arrays: one of integers, one of double precision numbers, and one of
   characters. Each element of these virtual arrays is pointed to by an
   integer known as a ``logical address.'' The logical addresses for each
   data type are independent: for each data type, the range of logical
   addresses starts at 1 and ends with the count of scalar data elements of
   that type. Thus an application program can, by calling DAS interface
   routines, read the ``100th through 200th integers'' or ``first through
   3000th characters'' from a DAS file.
<P>
 
   This simple view of the organization of data within a DAS file is
   independent of the order in which data are written to the file when it
   is created: double precision numbers, integers, and characters can be
   written to the file in an interleaved fashion, but the data of each type
   will still appear to be be contiguous to a program reading the file.
<P>
 
   The DAS suite of routines includes routines that convert DAS files
   between binary and transfer formats. DAS files in transfer format can be
   easily ported between computer systems having different binary numeric
   and character data representations. The SPICE Toolkit's TOBIN, TOXFR,
   and SPACIT utilities allow users to carry out these conversions via
   command-line or menu-based programs. Therefore, any high-level file
   format based on DAS can be ported using existing SPICE utilities.
<P>
 
   The task of adding annotation to data files is also solved by using the
   DAS format. The SPICE Toolkit's COMMNT utility can insert annotation
   into, or extract annotation from, any DAS file, so this capability is
   automatically available for any files having a format based on DAS.
<P>
 
   Because speed of file access can be important for programs that use
   large files, the DAS subsystem buffers in memory data that it reads from
   or writes to a DAS file. This buffering operation is completely
   independent of the I/O mechanism of the computer system on which a
   DAS-based application program runs. User-written access routines for any
   file format based on DAS will automatically support I/O buffering,
   simply by calling DAS routines to carry out their I/O operations.
<P>
 
<BR><BR>
<A NAME="Using the DAS Subsystem"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H1> Using the DAS Subsystem
</H1><HR SIZE=3 NOSHADE><P><BR><BR><BR>
   This chapter explains how to use the DAS subsystem in your own
   application program. The first section, titled ``Prerequisites,''
   discusses concepts that must be understood in order to read the
   discussion of the DAS routines that follows. The second section ``Using
   the DAS Subroutines'' introduces the DAS subroutines that are normally
   used by application programs.
<P>
 
<BR><BR>
<A NAME="Prerequisites"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Prerequisites
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
<BR><BR>
<A NAME="Logical Addresses"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Logical Addresses
</H3><P><BR><BR>
   As we've said, the DAS subsystem makes a DAS file look to an application
   program as though the data in the file were segregated into three
   virtual arrays, one each of character, integer, and double precision
   type. Any or all of these arrays may be empty. In DAS terminology, each
   element of any of these ``logical'' arrays is called a ``word.'' The
   phrases ``integer word,'' ``character word,'' and ``double precision
   word'' are used when specific data types are of interest. Character
   words are single characters.
<P>
 
   The DAS logical address of a given word is the index of that word within
   its virtual array. When necessary to avoid ambiguity, we'll use the
   phrases ``integer logical address,'' ``double precision logical
   address,'' or ``character logical address'' to denote logical addresses
   of words of each data type. Logical addresses themselves, wherever
   they're used in DAS routines, are represented by Fortran integers.
<P>
 
   The valid range of indices for each non-empty virtual array starts at 1
   and ends at the word count for that array. There are no ``holes'' in the
   arrays; every logical address in the valid range for an array points to
   data. This property of the virtual arrays is enforced by the mechanism
   by which DAS files are populated with data: data may be placed in a
   virtual array by either by appending or by updating a range of valid
   logical addresses. Random write access to array addresses outside of the
   valid range is not supported.
<P>
 
   The word counts for each logical array can be obtained via the routine
   DASLLA (``DAS, last logical addresses'').
<P>
 
   The ordering of the data within each virtual array is controlled by the
   order in which data are appended to that array. Each append operation
   adds the contents of a Fortran array to the DAS virtual array of the
   same data type. An append operation appends the elements of the Fortran
   array, in an order-preserving way, to a contiguous range of logical
   addresses, starting with the successor of the highest logical address
   already occupied in the virtual array. In the case of arrays of strings,
   the order of characters within an array increases from left to right,
   and all characters within an array element precede those belonging to
   any higher-indexed element.
<P>
 
<BR><BR>
<A NAME="Read and Write Access"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Read and Write Access
</H3><P><BR><BR>
   The DAS subsystem provides a measure of system-independent protection
   for files that are intended to be accessed in a ``read only'' fashion. A
   program can open a DAS file for ``read access'' or ``write access'';
   when a DAS file is opened for read access, it cannot be modified by the
   DAS routines. A DAS file opened for write access can be read as well as
   written.
<P>
 
   A program selects the access type of a DAS file by opening it with a
   call to the appropriate DAS routine: DASOPR opens files for read access;
   DASOPW opens existing DAS files for write access; and DASONW opens a new
   DAS file for write access. The routine DASOPS opens a new scratch DAS
   file for write access.
<P>
 
   A program is allowed to open a DAS file for read access multiple times
   during a single run, but once a file is opened for write access, any
   subsequent attempts to open it cause an error to be signaled.
<P>
 
   The file access restrictions imposed by the DAS subsystem do not pertain
   to access of a single DAS file by multiple programs. Limitations on this
   type of file access are system-dependent. However, NAIF recommends
   avoiding arrangements involving access by multiple programs to a DAS
   file that has been opened for writing by any one of them.
<P>
 
<BR><BR>
<A NAME="File Handles"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> File Handles
</H3><P><BR><BR>
   DAS routines that open DAS files return an integer argument called a
   ``file handle.'' Most DAS routines use file handles rather than file
   names or Fortran logical units to specify DAS files. File handles can be
   compared more reliably and quickly than file names. Unlike logical
   units, the characteristics of DAS file handles are system-independent.
<P>
 
   There is a one-to-one correspondence between file handles and DAS files
   that are known to a program. In particular, when a DAS file is opened
   for read access multiple times during a single program run, the same
   handle is returned each time.
<P>
 
   The DAS subsystem does not recycle handles: once a file handle is
   assigned to a file, that integer will not be assigned to a different
   file during the same program run, even if the file the handle is
   assigned to is closed. At any time, a list of handles of open DAS files
   can be obtained by calling the DAS utility DASHOF.
<P>
 
<BR><BR>
<A NAME="The DAS Comment Area"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> The DAS Comment Area
</H3><P><BR><BR>
   The DAS file architecture supports a data struture called the ``comment
   area.'' This feature allows sequence EKs to store free-form text
   comments. Comments may be labels or other descriptive text that fully
   identifies the file and indicates its intended purpose.
<P>
 
   The contents of the comment area must be printable text. The comment
   area is line-oriented; text inserted into the comment area can be
   retrieved with the original line breaks preserved. It is recommended
   that text to be inserted into the comment area have no lines exceeding
   80 characters in length.
<P>
 
<BR><BR>
<A NAME="Internal File Names"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Internal File Names
</H3><P><BR><BR>
   The DAS file format allows a 60-character string called an ``internal
   file name'' to be stored in a DAS file. Normally, this string is placed
   in the file when the file is created. The name may be retrieved at any
   time by calling DASRFR.
<P>
 
   The internal file name provides a mechanism for attaching an identifier
   to a DAS file in a manner independent of the file system on which the
   DAS file was created.
<P>
 
   The internal file name capability existed before the DAS comment area
   feature was developed; the comment area provides much greater
   flexibility in annotating DAS files. NAIF suggests the comment area,
   rather than the internal file name, be used for system-independent file
   identification.
<P>
 
<BR><BR>
<A NAME="Binary and Transfer DAS files"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Binary and Transfer DAS files
</H3><P><BR><BR>
   Since transfer files can be easily ported between different computer
   systems, but direct access, binary files cannot, the DAS subsystem
   provides routines that convert a binary DAS file to an equivalent
   transfer file, as well as routines that perform the inverse conversion.
<P>
 
   No SPICELIB routines other than the DAS conversion routines themselves
   depend on the DAS transfer format, and this format is not considered
   part of the DAS subsystem specification. Non-SPICELIB applications
   should avoid reliance on the specific format of DAS transfer files; this
   format may be updated by NAIF, though any previous transfer formats will
   continue to be supported.
<P>
 
   The transfer format has the property of preserving all of the character,
   double precision, and integer information in the virtual arrays of DAS
   file; in particular, the full precision of all numeric quantities is
   preserved when a binary DAS file in converted to transfer format and
   then back to binary format on the same computer.
<P>
 
<BR><BR>
<A NAME="Buffering"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Buffering
</H3><P><BR><BR>
   When the DAS subsystem reads a physical record from a DAS file, or when
   it writes a physical record, a copy of the data in that record is saved
   in memory. We call this ``buffering'' the record. The subsystem buffers
   a limited number of the most recently accessed records of each data
   type.
<P>
 
   Because the DAS subsystem buffers records, successive reads from or
   writes to the same record are generally more efficient than they would
   be if file I/O were performed in response to each read or write request.
   Because the DAS subsystem uses its own declared storage for buffering,
   this capability is guaranteed to be supported, regardless of the I/O
   buffering capabilities of the computer system on which the DAS subsystem
   is used.
<P>
 
   The buffering performed by the DAS subsystem is automatic, and the
   existence of this feature can normally be safely ignored. The cases
   where it must be taken into account are:
<P>
 
<UL>
<TT>--</TT> When the creation of a DAS file terminates abnormally
<BR><BR></UL>
<UL>
<TT>--</TT> When DAS file access speed must be optimized
<BR><BR></UL>
   In the first case, the contents of the DAS file may not contain all of
   the data ``written'' to the file by the DAS writing routines (DASADx and
   DASUDx), because some of that data may have been buffered but not
   written at the time the file creation was terminated.
<P>
 
   In the second case, adjusting the sizes of the buffer arrays in DASRWR
   may improve performance. The sizes of the arrays are parameterized, so
   it is easy to change them. However, modifying SPICELIB code can create a
   maintenance burden for the owner of the modified code, because in order
   to accept a SPICELIB update (which could contain bug fixes), it will be
   necessary to modify the new versions of any previously modified SPICELIB
   routines.
<P>
 
<BR><BR>
<A NAME="Using Multiple DAS Files Simultaneously"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Using Multiple DAS Files Simultaneously
</H3><P><BR><BR>
   A program may have multiple DAS files open at the same time. Normally,
   it should not be necessary to have more than two or three DAS files open
   simultaneously, but the DAS subsystem sets the limit at the somewhat
   indulgent value of 20 files.
<P>
 
   When a program accesses multiple DAS files at the same time, the
   program's interactions with each file are independent of the program's
   interactions with the other files. Any DAS routine that performs an
   operation on a DAS file accepts a handle, Fortran logical unit number,
   or file name input argument that identifies the file to be acted upon,
   so it is easy to ensure that a program accesses the correct files.
<P>
 
   Accessing multiple DAS files simultaneously may affect a program's speed
   of execution, since all of the files compete for the same space in the
   DAS record buffers.
<P>
 
<BR><BR>
<A NAME="DAS vs DAF"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> DAS vs DAF
</H3><P><BR><BR>
   The DAS subsystem is, roughly speaking, a generalization of the DAF
   subsystem, since DAS supports storage of integer and character data as
   well as double precision data, whereas the DAF subsystem supports
   storage of double precision data only. The DAF format can easily be
   ``simulated'' using as DAS file.
<P>
 
   On the other hand, the DAF subsystem provides higher-level services that
   are not built into DAS: in the DAF subsystem, the data are partitioned
   into a linked list of virtual arrays, each one having its own name and
   descriptor, and the subsystem provides routines to manipulate the arrays
   and their descriptive information. This capability can be added to DAS,
   but DAS files are not required to have this structure.
<P>
 
<BR><BR>
<A NAME="Using DAS Subroutines"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Using DAS Subroutines
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   This section shows how common functions involving DAS files are carried
   out.
<P>
 
   In the code examples shown in this chapter, we'll display a brief phrase
   describing the function of each DAS routine that appears in the code, as
   shown below:
<P>
 
<PRE>
   CALL DASCLS ( HANDLE )                             {Close DAS file}
</PRE>
<BR><BR>
<A NAME="Creating a New DAS File"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Creating a New DAS File
</H3><P><BR><BR>
   New DAS files are created by calling DASONW:
<P>
 
<PRE>
   CALL DASOPN ( FNAME, FTYPE, IFNAME, NCOMR, HANDLE )
 
                                                   {Open new DAS file}
</PRE>
   Here FNAME, FTYPE, IFNAME and NCOMR are inputs, and HANDLE is an output.
   FNAME is the name of the new file to be created, IFNAME is the internal
   file name of the new file, and NCOMR is the number of comment records to
   reserve. .HANDLE is the integer handle assigned to the DAS file by
   DASOPN.
<P>
 
   After this call, the DAS file is ready to be populated with data.
<P>
 
<BR><BR>
<A NAME="Writing DAS Files"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Writing DAS Files
</H3><P><BR><BR>
   There are two ways to write data to a DAS file: data can be added to the
   file by appending it to the virtual arrays, and data already in the
   virtual arrays can be updated.
<P>
 
   The routines DASADC, DASADD, and DASADI are used to add data to DAS
   files. These routines append data to the file's character, double
   precision, or integer logical arrays. As an example, we'll add some data
   of each type to the file FNAME from the example above. We'll start out
   with integer data.
<P>
 
   DASADI adds the contents of an integer array to a DAS file. In the call
   below, the argument HANDLE identifies the file, the number 100 is the
   number of elements in the data array, and DATAI is an array of integers
   whose contents are to be appended to the integer virtual array.
<P>
 
<PRE>
   DO I = 1, 100
      DATAI(I) = I
   END DO
 
   CALL DASADI ( HANDLE, 100, DATAI )              {Add data, integer}
</PRE>
   DASADD is the double precision analog of DASADI. Since the logical
   arrays of different data types are independent, the double precision
   data from the array DATAD will occupy double precision logical addresses
   1 through 100.
<P>
 
<PRE>
   DO I = 1, 100
      DATAD(I) = DBLE(I)
   END DO
 
   CALL DASADD ( HANDLE, 100, DATAD )     {Add data, double precision}
</PRE>
   DASADC is the character analog of DASADI. The second argument to DASADC
   indicates the total number of character logical addresses to be filled.
   DASADC has two additional input arguments that DASADI and DASADD do not
   have: begin and end substring bounds that indicate which portion of the
   array of input strings to transfer data from.
<P>
 
   In this case, we'll presume that the array DATAC is declared
<P>
 
<PRE>
   CHARACTER*(80)            DATAC ( 2 )
</PRE>
<PRE>
   DATAC(1) = 'Here''s the first line of character data.'
   DATAC(2) = 'And here''s the second line.'
</PRE>
   The call below will write the contents of elements 1:2 of DATAC to DAS
   logical character addresses 1:160, because all of the characters of each
   element of DATAC are written to the file.
<P>
 
<PRE>
   CALL DASADC ( HANDLE, 2, 1, 80, DATAC )       {Add data, character}
</PRE>
   If we don't wish to write out all 80 characters of each element of
   DATAC, we can use different substring bounds in the call to DASADC. As
   an example, we'll add two more lines to the file, this time using only
   characters 1 through 50 in each element of DATAC:
<P>
 
<PRE>
   DATAC(1) = 'This is the third line.'
   DATAC(2) = 'This is the fourth line.'
 
   CALL DASADC ( HANDLE, 2, 1, 50, DATAC )       {Add data, character}
</PRE>
   This call added only 100 characters to the file.
<P>
 
   We can continue to add data of any type to the file at this point. As an
   example, we'll add 100 more integers to the file.
<P>
 
<PRE>
   DO I = 1, 100
      DATAI(I) = I + 100
   END DO
 
   CALL DASADI ( HANDLE, 100, DATAI )              {Add data, integer}
</PRE>
   In addition to appending data to the virtual arrays in a DAS file, you
   can update array elements whose values have already been set. The DAS
   update routines are DASUDC, DASUDD, and DASUDI, which accept input
   arrays of character strings, double precision numbers, and integers,
   respectively.
<P>
 
   It is not always convenient to set the values of the elements of a DAS
   file's virtual arrays in strictly increasing order; using the update
   capability, a program can fill in array elements with placeholder
   values, then update those values when their actual values are known.
<P>
 
   To continue the example, we could update the first 100 integers in the
   file by negating them:
<P>
 
<PRE>
   DO I = 1, 100
      DATA(I) = -I
   END DO
 
   CALL DASUDI ( HANDLE, 1, 100, DATA )           {Update data,
                                                   integer}
</PRE>
   The routines DASUDD and DASUDC update double precision and character
   data in an analogous way.
<P>
 
   To complete the new DAS file we've created, we close it using the
   routine DASCLS:
<P>
 
<PRE>
   CALL DASCLS ( HANDLE )                         {Close DAS file}
</PRE>
   DAS files should never be closed directly by a Fortran CLOSE statement.
   In particular, DAS files that have been written to may not contain all
   of the data written unless DASCLS is used to close them.
<P>
 
   At this point, the virtual arrays in our example DAS file have the
   following contents:
<P>
 
<PRE>
   Integer virtual array
   ---------------------
 
                                                  +-----+
        Integer logical address #1                | -1  |
                                                  +-----+
                                                     .
                                                     .
                                                     .
                                                  +-----+
        Integer logical address #100              |-100 |
                                                  +-----+
        Integer logical address #101              | 101 |
                                                  +-----+
                                                     .
                                                     .
                                                     .
                                                  +-----+
        Integer logical address #200              | 200 |
                                                  +-----+
 
</PRE>
<PRE>
   Double precision virtual array
   ------------------------------
 
                                                  +-----+
        Double precision logical address #1       |1.D0 |
                                                  +-----+
                                                     .
                                                     .
                                                     .
                                                  +-----+
        Double precision logical address #100     |1.D2 |
                                                  +-----+
</PRE>
<PRE>
   Character virtual array
   -----------------------
 
                                                  +---+
        Character logical address #1              | H |
                                                  +---+
                                                  | e |
                                                  +---+
                                                  | r |
                                                  +---+
                                                  | e |
                                                  +---+
                                                  | ' |
                                                  +---+
                                                  | s |
                                                  +---+
                                                    .
                                                    .
                                                    .
                                                  +---+
        Character logical address #80             |   |
                                                  +---+
        Character logical address #81             | A |
                                                  +---+
                                                  | n |
                                                  +---+
                                                  | d |
                                                  +---+
                                                    .
                                                    .
                                                    .
                                                  +---+
        Character logical address #160            |   |
                                                  +---+
        Character logical address #161            | T |
                                                  +---+
                                                  | h |
                                                  +---+
                                                  | i |
                                                  +---+
                                                  | s |
                                                  +---+
                                                    .
                                                    .
                                                    .
                                                  +---+
        Character logical address #210            |   |
                                                  +---+
        Character logical address #211            | T |
                                                  +---+
                                                  | h |
                                                  +---+
                                                  | i |
                                                  +---+
                                                  | s |
                                                  +---+
                                                    .
                                                    .
                                                    .
                                                  +---+
        Character logical address #260            |   |
                                                  +---+
 
</PRE>
<BR><BR>
<A NAME="Writing to an Existing DAS file"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Writing to an Existing DAS file
</H3><P><BR><BR>
   The DASADx and DASUDx routines described above can be used to write to
   an old DAS file (one that contains data and is not currently open), as
   well as to a newly created one. To write to an old DAS file, open it for
   writing using DASOPW:
<P>
 
<PRE>
   CALL DASOPW ( FNAME, HANDLE )                  {Open DAS file for
                                                   writing}
</PRE>
   After this call, the DASADx and DASUDx routines can be used to add data
   to the file and update data in the file.
<P>
 
   When the modification of the DAS file is complete, the file should be
   closed using DASCLS.
<P>
 
<BR><BR>
<A NAME="Reading DAS Files"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Reading DAS Files
</H3><P><BR><BR>
   The DAS reading routines are DASRDC, DASRDD, and DASRDI. Each of these
   routines reads data from a range of logical addresses. These routines
   can read from a DAS file that is open for reading or writing.
<P>
 
   We'll continue our example by showing the results of reading the file we
   created.
<P>
 
   We start out by reading a range of integer addresses. After the
   following sequence of calls, the array DATAI will contain the integers
   101 through 200.
<P>
 
<PRE>
   CALL DASOPR ( FNAME,  HANDLE )          {Open DAS file for reading}
 
   CALL DASRDI ( HANDLE, 101, 200, DATAI )        {Read data, integer}
</PRE>
   The following call will fill the array DATAI with the integers -1
   through -100:
<P>
 
<PRE>
   CALL DASRDI ( HANDLE, 1, 100, DATAI )          {Read data, integer}
</PRE>
   We can retrieve the double precision data from the file using DASRDD.
   The following call will fill the array DATAD with the values 1.D0
   through 1.D2:
<P>
 
<PRE>
   CALL DASRDD ( HANDLE, 1, 100, DATAD )          {Read data, double
                                                   precision}
</PRE>
   Now for the character data: we'll read the data written by DASADC using
   DASRDC. After the call
<P>
 
<PRE>
   CALL DASRDC ( HANDLE, 1,160, 1, 80, DATAC )    {Read data, character}
</PRE>
   the array DATAC (whose elements have a length of 80 characters) will
   contain the lines
<P>
 
<PRE>
   DATAC(1) = 'Here''s the first line of character data.'
   DATAC(2) = 'And here''s the second line.'
</PRE>
   Both elements of DATAC will be padded with trailing blanks.
<P>
 
   A second call
<P>
 
<PRE>
   CALL DASRDC ( HANDLE, 161, 260, 1, 50, DATAC )
</PRE>
   will make the substring assignments
<P>
 
<PRE>
   DATAC(1)(1:50) =  'This is the third line.'
   DATAC(2)(1:50) =  'This is the fourth line.'
</PRE>
   The character substrings DATAC(1)(51:80) and DATAC(2)(51:80) are left
   unchanged by this call.
<P>
 
<BR><BR>
<A NAME="Converting Between Binary and Transfer Format"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Converting Between Binary and Transfer Format
</H3><P><BR><BR>
   The DAS subsystem contains two routines that convert between DAS binary
   and transfer format. These are:
<P>
 
<PRE>
   DASBT
   DASTB
</PRE>
   DASBT converts a binary DAS file to transfer format.
<P>
 
<PRE>
   CALL DASBT ( DAS, XFRLUN )         {Convert DAS to transfer file}
 
</PRE>
   .
<P>
 
   DASTB is the inverse of this routine.
<P>
 
<PRE>
   CALL DASTB( XFRLUN, DAS )        {Convert transfer file to DAS}
 
</PRE>
   Since the SPICE Toolkit utility programs TOBIN and TOXFR are able to
   convert between binary and transfer DAS formats, SPICE Toolkit users
   should rarely need to make direct use of these conversion routines.
<P>
 
<BR><BR>
<A NAME="Annotating DAS Files"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Annotating DAS Files
</H3><P><BR><BR>
   The comment area of a DAS file may be used to store comments in an
   encoded form. This capability is supported by the SPICELIB SPC routines:
   using those routines the comments of a text file may be stored in the
   comment are, and text stored in this way may be extracted again to a
   text file. See the SPC Required Reading, <a href="../req/spc.html">spc.req</a>, for documentation of
   these routines.
<P>
 
   Normally, SPICELIB users will not need to manipulate the comment area
   using DAS API routines; the basic functionality of storing comments in a
   DAS file and extracting stored comments is provided by the SPICE Toolkit
   utility COMMNT. See the COMMNT user's guide, <a href="../ug/commnt.html">commnt.ug</a>, for details.
<P>
 
<BR><BR>
<A NAME="Mapping Between Handles, File Names, and Units"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Mapping Between Handles, File Names, and Units
</H3><P><BR><BR>
   Given a valid DAS handle, the corresponding file name and Fortran
   logical unit can be found by calling the appropriate DAS routine:
<P>
 
<PRE>
   CALL DASHFN ( HANDLE, FNAME )            { Handle to file name    }
   CALL DASHLU ( HANDLE, UNIT  )            { Handle to logical unit }
</PRE>
   For completeness, the inverse mapping routines are supplied:
<P>
 
<PRE>
   CALL DASFNH ( FNAME, HANDLE )            { File name to handle    }
   CALL DASLUH ( UNIT,  HANDLE )            { Logical unit to handle }
</PRE>
<BR><BR>
<A NAME="Obtaining a DAS File Summary"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Obtaining a DAS File Summary
</H3><P><BR><BR>
   Occasionally, an application program may need to know the range of
   logical addresses in use within a DAS file. This information can be
   obtained from the file's summary, which is returned by DASHFS:
<P>
 
<PRE>
   CALL DASHFS ( HANDLE, NRESV, FREE, LASTLA, LASTRC, LASTWD )
 
                                           { Handle to file summary }
</PRE>
   The desired information is in the output argument LASTLA, which is an
   array of the last logical addresses of character, double precision, and
   integer types, in that order. Given only this information, a program can
   read the contents of the file by using the DASRDx routines.
<P>
 
   The other arguments of DASHFS will probably be of interest only to
   programmers creating new DAS subroutines. See the header of DASHFS for
   further information.
<P>
 
<BR><BR>
<A NAME="Using Scratch DAS Files"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Using Scratch DAS Files
</H3><P><BR><BR>
   DAS files can be opened with a Fortran status of 'SCRATCH'. Scratch DAS
   files are always opened for write access. When they are closed, they are
   automatically deleted.
<P>
 
   To obtain a scratch DAS file, use the routine DASOPS:
<P>
 
<PRE>
   CALL DASOPS ( HANDLE )                    { Open scratch DAS file }
</PRE>
   Here HANDLE is an output argument. DASOPS does not take a file name
   input argument because ANSI Standard Fortran 77 does not allow
   assignment of file names to scratch files. Since the file is temporary,
   there is no need to give it an internal file name or to reserve records
   in it.
<P>
 
   As with any other DAS file, scratch DAS files should be closed by
   calling DASCLS.
<P>
 
   Application programs that need large amounts of temporary work space and
   that must be able to access that work space randomly can take advantage
   of the DAS subsystem: scratch DAS files are direct access files, provide
   buffered read and write access, and have the same simple interface as do
   permanent DAS files.
<P>
 
<BR><BR>
<A NAME="DAS Architecture"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H1> DAS Architecture
</H1><HR SIZE=3 NOSHADE><P><BR><BR><BR>
   The information in this section is provided for the sake of
   completeness; most SPICELIB users, including those designing their own
   DAS-based formats, will not need to know the details of the DAS
   architecture. NAIF strongly recommends that SPICELIB-based application
   programs access DAS files only through SPICELIB DAS access routines,
   which make the DAS format transparent to the calling program.
<P>
 
<BR><BR>
<A NAME="Overview of DAS Architecture"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Overview of DAS Architecture
</H3><P><BR><BR>
   DAS files are Fortran direct access files having a record length long
   enough so that NWD double precision numbers, NWI integers, or NWC
   characters can fit in a single record. The values of these parameters
   are:
<P>
 
<PRE>
   NWC  =  1024
   NWD  =   128
   NWI  =   256
</PRE>
   Each record in a DAS file is dedicated to a specific purpose; records
   either contain data or control information that describes the structure
   and contents of the file. The types of records are:
<P>
 
<UL>
<TT>--</TT> File records
<BR><BR></UL>
<UL>
<TT>--</TT> Comment records
<BR><BR></UL>
<UL>
<TT>--</TT> Directory records
<BR><BR></UL>
<UL>
<TT>--</TT> Character data records
<BR><BR></UL>
<UL>
<TT>--</TT> Double precision data records
<BR><BR></UL>
<UL>
<TT>--</TT> Integer data records
<BR><BR></UL>
   As the above list implies, each data record contains data of only one
   type.
<P>
 
   Every DAS file contains one file record, which is always the first
   record of the DAS file. Comment records are optional. All DAS files
   contain at least one directory record, and useful DAS files also contain
   at least one data record.
<P>
 
   The diagram below shows how records of different types are grouped
   within a general binary DAS file. The parenthesized numbers at the right
   indicate the number of records within the named group on the left.
<P>
 
<PRE>
   +------------------------+
   |      file record       |   ( 1 )
   +------------------------+
   |    reserved records    |   ( NRESVR )
   +------------------------+
   |                        |
   |                        |
   |    comment records     |   ( NCOMR )
   |                        |
   |                        |
   +------------------------+
   | first data directory   |   ( 1 )
   +------------------------+
   |      data records      |
   |                        |   ( variable )
   |                        |
   +------------------------+
               .
               .
               .
   +------------------------+
   | last data directory    |   ( 1 )
   +------------------------+
   |     data records       |
   |                        |   ( variable )
   |                        |
   +------------------------+
</PRE>
   Normally, when a new DAS file is closed, the data records are segregated
   into contiguous sets of records of each data type present in the file.
   The format of a DAS file after this re-organization is shown below:
<P>
 
<PRE>
   +------------------------+
   |      file record       |   ( 1 )
   +------------------------+
   |    reserved records    |   ( variable )
   +------------------------+
   |    comment records     |
   |                        |   ( variable )
   |                        |
   +------------------------+
   | first data directory   |   ( 1 )
   +------------------------+
   | character data records |
   |                        |   ( variable )
   |                        |
   +------------------------+
   |   d.p. data records    |
   |                        |   ( variable )
   |                        |
   +------------------------+
   |  integer data records  |
   |                        |   ( variable )
   |                        |
   +------------------------+
</PRE>
   The purpose of the re-organization is to simplify the process of mapping
   logical addresses to physical locations in the file, thereby speeding up
   access to data.
<P>
 
   Note that the structure of the re-organized DAS file is just a special
   case of the general structure. All of the DAS routines that make
   explicit use of the structure of DAS files are equipped to work with the
   general structure: it is never assumed that data segregation has taken
   place.
<P>
 
<BR><BR>
<A NAME="The File Record"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> The File Record
</H3><P><BR><BR>
   The file record contains the following information about the DAS file
   containing it:
<P>
 
<UL>
<TT>--</TT> An ID word
<BR><BR></UL>
<UL>
<TT>--</TT> The internal file name
<BR><BR></UL>
<UL>
<TT>--</TT> The reserved record count
<BR><BR></UL>
<UL>
<TT>--</TT> The reserved character count
<BR><BR></UL>
<UL>
<TT>--</TT> The comment record count
<BR><BR></UL>
<UL>
<TT>--</TT> The comment character count
<BR><BR></UL>
<UL>
<TT>--</TT> The FTP error detection string
<BR><BR></UL>
<UL>
<TT>--</TT> The binary file format identification string
<BR><BR></UL>
   The ID word is a character string that identifies the file as a DAS
   file, as opposed to a DAF or some other type of file. The ID word
   contains eight characters, the first four of which are
<P>
 
<PRE>
   DAS/
</PRE>
   The contents of the file record are organized as follows:
<P>
 
<PRE>
   +-------------------------------------------------------+
   |IDWORD|IFNAME|NRR|NRC|NCR|NCC|&lt;unused&gt;|FTP|&lt;unused&gt;|BFF|
   +-------------------------------------------------------+
</PRE>
   where the abbreviations represent:
<P>
 
<DL><DT>
<B>
 `idword'
</B><BR><BR>
<DD>
 is the DAS ID word.<BR>
</DL>
<DL><DT>
<B>
 `ifname'
</B><BR><BR>
<DD>
 is the internal file name.<BR>
</DL>
<DL><DT>
<B>
 `nrr'
</B><BR><BR>
<DD>
 is the number of reserved records.<BR>
</DL>
<DL><DT>
<B>
 `nrc'
</B><BR><BR>
<DD>
 is the number of reserved characters---the number of characters in use
in the reserved record area.<BR>
</DL>
<DL><DT>
<B>
 `ncr'
</B><BR><BR>
<DD>
 is the number of comment records.<BR>
</DL>
<DL><DT>
<B>
 `ncc'
</B><BR><BR>
<DD>
 is the number of comment characters---the number of characters in use
in the comment area.<BR>
</DL>
<DL><DT>
<B>
 `bff'
</B><BR><BR>
<DD>
 is the FTP error detection string.<BR>
</DL>
<DL><DT>
<B>
 `bff'
</B><BR><BR>
<DD>
 is the binary file format identifier.<BR>
</DL>
   The file record can be read and updated at run time using DASRFR and
   DASWFR. DASRFR is normally used to read the internal file name of a DAS
   file. On the other hand, non-SPICELIB code should rarely, if ever, need
   to update the file record.
<P>
 
<BR><BR>
<A NAME="Reserved Records"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Reserved Records
</H3><P><BR><BR>
   The reserved record area is a data structure that serves as a hook for
   future development. SPICE users normally will have no reason to access
   reserved records, and indeed the DAS API supplies no access methods for
   these records.
<P>
 
   Reserved records play no role in DAS operations, but their number must
   be known by the DAS subsystem. The number is set when a DAS file is
   created, and is automatically updated at run time if reserved records
   are added by calling DASARR.
<P>
 
<BR><BR>
<A NAME="Comment Records"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Comment Records
</H3><P><BR><BR>
   Comment records are character records that constitute the DAS comment
   area.
<P>
 
<BR><BR>
<A NAME="Directory Records"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Directory Records
</H3><P><BR><BR>
   Directory records, or ``directories,'' are records that allow the DAS
   subsystem to find the physical location in a DAS file corresponding to a
   specified logical address.
<P>
 
   Each directory record describes the data types of a number of data
   records that follow. Each directory also contains, for each data type,
   the lowest and highest logical address occurring in any of the records
   described by the directory.
<P>
 
   The directories in a DAS file form a doubly linked list: each directory
   contains forward and backward pointers to the next and previous
   directories. Thus the list of directory records in a DAS can be viewed
   as shown below:
<P>
 
<PRE>
      NIL
       ^     +---------------------------------------------------+
       |     |                                                   |
       `-----|                                                   |
             |           First Directory Record                  |
       .----&gt;|                                                   |
       |  .--|                                                   |
       |  |  +---------------------------------------------------+
       |  |                       .
       |  |                       .
       |  |                       .
       |  |  +---------------------------------------------------+
       |  `-&gt;|                                                   |
       `-----|                                                   |
             |           Second Directory Record                 |
       .----&gt;|                                                   |
       |  .--|                                                   |
       |  |  +---------------------------------------------------+
       |  |
 
       .  .                       .
       .  .                       .
       .  .                       .
 
       |  |
       |  |  +---------------------------------------------------+
       |  `-&gt;|                                                   |
       `-----|                                                   |
             |            Last Directory Record                  |
             |                                                   |
          .--|                                                   |
          |  +---------------------------------------------------+
          V
         NIL
</PRE>
   After data segregation, the list of directories contains a single
   record.
<P>
 
   The structure of each directory record is as follows:
<P>
 
<PRE>
   +-----------------------------------------------------------------+
   | &lt;pointers&gt; | &lt;address ranges&gt; |      &lt;cluster descriptors&gt;      |
   +-----------------------------------------------------------------+
</PRE>
   where the
<P>
 
<PRE>
   &lt;pointers&gt;
</PRE>
   section looks like
<P>
 
<PRE>
   +-----------------------------------------+
   | &lt;backward pointer&gt; | &lt;forward pointer&gt; |
   +-----------------------------------------+
</PRE>
   the
<P>
 
<PRE>
   &lt;address ranges&gt;
</PRE>
   section looks like
<P>
 
<PRE>
   +-------------------------------------------+
   | &lt;char range&gt; | &lt;d.p. range&gt; | &lt;int range&gt; |
   +-------------------------------------------+
</PRE>
   and each range looks like one of:
<P>
 
<PRE>
   +------------------------------------------------+
   | &lt;lowest char address&gt; | &lt;highest char address&gt; |
   +------------------------------------------------+
 
   +------------------------------------------------+
   | &lt;lowest d.p. address&gt; | &lt;highest d.p. address&gt; |
   +------------------------------------------------+
 
   +------------------------------------------------+
   | &lt;lowest int address&gt;  | &lt;highest int address&gt;  |
   +------------------------------------------------+
</PRE>
   When the set of data records described by a directory record contains no
   data of a given type, the address range corresponding to that type is
   0:0.
<P>
 
   Following the pointers and address range information is a sequence of
   cluster descriptors. ``Clusters'' are maximal, contiguous sequences of
   data records of a given data type. By ``maximal'' we mean that each
   cluster is preceded and followed by a record that is not a data record
   of the cluster's type. Each cluster descriptor indicates the data type
   and record count of the cluster it describes. Successive cluster
   descriptors map to successive clusters of data records in the file, as
   shown below:
<P>
 
<PRE>
   +---------------------------------------------------+
   |    . . . | DESCR(i)  | DESCR(i+1) | . . .         | Directory
   +---------------|----------|------------------------+
                   |        . |
                   |        . |
                   |        . |
   +---------------|----------|------------------------+
   |               |          |                        | Data records
   |               V          |    Cluster (i)         |
   |                          |                        |
   +--------------------------|------------------------+
   |                          |                        |
   |                          V    Cluster (i+1)       |
   |                                                   |
   |                                                   |
   |                                                   |
   +---------------------------------------------------+
                            .
                            .
                            .
</PRE>
   Note that although the number of cluster descriptors in a directory
   record is limited, the number of records described by a directory is
   virtually arbitrary, because the number of records in each cluster may
   vary. In particular, after data segregation is performed, a DAS file
   will contain only three clusters and requires a single directory in
   order to describe those clusters.
<P>
 
   The cluster descriptors are implemented using a run-length encoding
   scheme. The first element of the series of descriptors occupies two
   integers; these represent a type code and a count. The rest of the
   descriptors are just signed counts; the data types of the clusters they
   describe are determined by the sign of the count and the data type of
   the previous descriptor.
<P>
 
<BR><BR>
<A NAME="Data Records"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Data Records
</H3><P><BR><BR>
   Each DAS data record contains data of only one type.
<P>
 
   Within each DAS data record, word numbers start at one and increase up
   to NWI, NWD, or NWC: the number of words in an integer, double
   precision, or character data record. The organization of data records
   can be thought of as follows:
<P>
 
<PRE>
 
   Character records
   -----------------
 
        +------------------------------------+
        | | |           ...                | |
        +------------------------------------+
         1 2                               NWC
 
 
   Double precision records
   ------------------------
 
        +--------------------------------+
        |       |       |   ...  |       |
        +--------------------------------+
            1      2                NWD
 
 
   Integer records
   ---------------
 
        +--------------------------------+
        |   |   |       ...          |   |
        +--------------------------------+
          1   2                       NWI
 
</PRE>
   Each data word in a DAS file is unambiguously specified by its type, the
   number of the record containing it, and its word number.
<P>
 
<BR><BR>
<A NAME="DAS Routines"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H1> DAS Routines
</H1><HR SIZE=3 NOSHADE><P><BR><BR><BR>
<BR><BR>
<A NAME="Summary of Mnemonics"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Summary of Mnemonics
</H3><P><BR><BR>
   All of the subroutines in the DAS family have names beginning with the
   letters ``DAS,'' followed by a two- or three-character mnemonic. For
   example, the routine that reads integer data from a DAS file is named
   DASRDI, pronounced ``DAS-R-D-I.'' The following is a complete list of
   mnemonics and translations, in alphabetical order.
<P>
 
<PRE>
   A2L  Map logical address to physical location
   AC   Add comments from buffer to file
   ACR  Add comment records to file
   ACU  Add comment records from logical unit to DAS file
   ADC  Add character data to file
   ADD  Add double precision data to file
   ADI  Add integer data to file
   BTU  Convert binary to text file
   CLS  Close file
   CUD  Create and update directories
   DC   Delete comments
   EC   Extract DAS comments into buffer
   ECU  Extract DAS comments to logical unit
   FM   File manager
   FNH  Map file name to handle
   HFN  Map handle to file name
   HFS  Map handle to file summary
   HLU  Map handle to logical unit
   HOF  Return handles of open DAS files
   IOC  Low-level character record I/O
   IOD  Low-level double precision record I/O
   IOI  Low-level integer record I/O
   LLC  Low-level file close
   LUH  Map logical unit to handle
   OPN  Open a new DAS file
   OPR  Open a DAS file for reading
   OPS  Open a scratch DAS file
   OPW  Open an existing DAS file for writing
   RDC  Read character data
   RDD  Read double precision data
   RDI  Read integer data
   RFR  Read file record
   RRC  Perform buffered read of character record
   RRD  Perform buffered read of double precision record
   RRI  Perform buffered read of integer record
   RWR  Read and write records
   SDR  Segregate data records
   SIH  Signal invalid handles
   TB   Convert text file to binary
   UDC  Update character data
   UDD  Update double precision data
   UDI  Update integer data
   UFS  Update file summary
   URC  Update character record
   URD  Update double precision record
   URI  Update integer record
   WBR  Write buffered records
   WFR  Write file record
   WRC  Perform buffered write of character record
   WRD  Perform buffered write of double precision record
   WRI  Perform buffered write of integer record
</PRE>
<BR><BR>
<A NAME="Summary of Calling Sequences"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Summary of Calling Sequences
</H3><P><BR><BR>
   Calling sequences of the DAS family of routines are given below.
   Routines are grouped according to function.
<P>
 
   The following routines are intended for use by both SPICELIB users'
   application programs and by SPICELIB routines.
<P>
 
   Opening and closing files:
<P>
 
<PRE>
   DASOPN ( FNAME, IFNAME, NRESV, HANDLE )
   DASOPW ( FNAME, HANDLE )
   DASOPR ( FNAME, HANDLE )
   DASOPS ( HANDLE )
   DASCLS ( HANDLE )
</PRE>
   Adding data to files:
<P>
 
<PRE>
   DASADC ( HANDLE, N, BPOS, EPOS, DATA )
   DASADD ( HANDLE, N,             DATA )
   DASADI ( HANDLE, N,             DATA )
</PRE>
   Updating data in files:
<P>
 
<PRE>
   DASUDC ( HANDLE, FIRST, LAST, BPOS, EPOS, DATA )
   DASUDD ( HANDLE, FIRST, LAST,             DATA )
   DASUDI ( HANDLE, FIRST, LAST,             DATA )
</PRE>
   Reading data from files:
<P>
 
<PRE>
   DASRDC ( HANDLE, FIRST, LAST, BPOS, EPOS, DATA )
   DASRDD ( HANDLE, FIRST, LAST,             DATA )
   DASRDI ( HANDLE, FIRST, LAST,             DATA )
</PRE>
   Mapping between file names, handles, and logical units:
<P>
 
<PRE>
   DASHLU ( HANDLE, UNIT   )
   DASHFN ( HANDLE, FNAME  )
   DASLUH ( UNIT,   HANDLE )
   DASFNH ( FNAME,  HANDLE )
</PRE>
   Conversion between binary and transfer format:
<P>
 
<PRE>
   DASBT ( BINARY, UNIT   )
   DASTB ( UNIT,   BINARY )
</PRE>
   File record (and internal file name) access:
<P>
 
<PRE>
   DASRFR ( HANDLE, IDWORD, IFNAME, NRESV )
   DASWFR ( HANDLE, IDWORD, IFNAME, NRESV )
</PRE>
   File summary access:
<P>
 
<PRE>
   DASHFS ( HANDLE, NRESV, FREE, LASTLA, LASTRC, LASTWD )
   DASUFS ( HANDLE, NRESV, FREE, LASTLA, LASTRC, LASTWD )
</PRE>
   Adding and extracting comment records:
<P>
 
<PRE>
   DASACR ( HANDLE, N )
   DASAC  ( HANDLE, N, BUFFER )
   DASACU ( COMLUN, BEGMRK, ENDMRK, INSBLN, HANDLE )
   DASEC  ( HANDLE, N )
   DASECR ( HANDLE, N, BUFFER )
</PRE>
   The following routines are considered to be utilities and generally will
   not need to be called by application programs.
<P>
 
   Buffered writing, updating, and reading of records:
<P>
 
<PRE>
   DASWRC ( HANDLE, RECNO, RECC )
   DASWRD ( HANDLE, RECNO, RECD )
   DASWRI ( HANDLE, RECNO, RECI )
   DASURC ( HANDLE, RECNO, FIRST, LAST, DATAC )
   DASURD ( HANDLE, RECNO, FIRST, LAST, DATAD )
   DASURI ( HANDLE, RECNO, FIRST, LAST, DATAI )
   DASRRC ( HANDLE, RECNO, FIRST, LAST, DATAC )
   DASRRD ( HANDLE, RECNO, FIRST, LAST, DATAD )
   DASRRI ( HANDLE, RECNO, FIRST, LAST, DATAI )
</PRE>
   Flushing buffer contents to files:
<P>
 
<PRE>
   DASWBR ( HANDLE )
</PRE>
   Low-level file I/O:
<P>
 
<PRE>
   DASIOC ( ACTION, UNIT, RECNO, RECC )
   DASIOD ( ACTION, UNIT, RECNO, RECD )
   DASIOI ( ACTION, UNIT, RECNO, RECI )
</PRE>
   Logical address to physical location mapping:
<P>
 
<PRE>
   DASA2L ( HANDLE, TYPE, ADDRSS, CLBASE, CLSIZE, RECNO, WORDNO )
</PRE>
   Directory creation and updating:
<P>
 
<PRE>
   DASCUD ( HANDLE, TYPE, NWORDS )
</PRE>
   Segregating data records:
<P>
 
<PRE>
   DASSDR ( HANDLE )
</PRE>
   File handle verification:
<P>
 
<PRE>
   DASHOF ( HSET )
   DASSIH ( HANDLE, ACCESS )
   DASHAM ( HANDLE, ACCESS )
</PRE>
   Low-level file close utility:
<P>
 
<PRE>
   DASLLC ( HANDLE )
</PRE>
   The following routines are umbrella subroutines. These should never be
   called, but their headers may be of interest to general SPICELIB users,
   since they contain ``global'' documentation pertaining to the routines'
   entry points.
<P>
 
<PRE>
   DASFM
   DASRWR
</PRE>
<BR><BR>
<A NAME="Examples"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H1> Examples
</H1><HR SIZE=3 NOSHADE><P><BR><BR><BR>
<BR><BR>
<A NAME="Storing a Symbol Table in a DAS File"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Storing a Symbol Table in a DAS File
</H3><P><BR><BR>
   This example shows how the contents of a SPICELIB double precision
   symbol table can be stored in and retrieved from a DAS file. The source
   code for two subroutines WRSYMD and RDSYMD that perform the write and
   read functions is listed below. With a small number of changes, the code
   shown here could be modified to deal with integer or character symbol
   tables.
<P>
 
   An important fact about user-designed, DAS-based formats is illustrated
   by this example: the high level format of a file must be understood by
   the code that reads the file, as well as the code that writes it.
   Therefore, most non-trivial user-designed formats will need to include a
   data structure that describes the rest of the file, thereby allowing the
   user's file reader to know how to read the file. In the following
   example, this data structure is very simple: it is a series of three
   integers whose meanings are known to the reader.
<P>
 
   The routines WRSYMD and RDSYMD could be used to implement the capability
   of loading binary PCK files into the SPICELIB kernel pool; such binary
   files would load faster than text kernels because it is not necessary to
   parse their contents when they're loaded.
<P>
 
   A SPICELIB double precision symbol consists of three arrays: an array of
   symbol names, an array of integers that serves to map names to their
   associated values, and an array of double precision values. WRSYMD adds
   the contents of a symbol table to a DAS file opened by the calling
   application. For each symbol, WRSYMD will add to the DAS file the
   symbol's name, the count of the values associated with that symbol, and
   the values associated with the symbol. In addition, the number of
   symbols in the symbol table, the total number of values associated with
   the symbols, and the length of the strings containing the symbols' names
   will be added to the file. The logical format of the resulting file can
   be thought of as follows:
<P>
 
<PRE>
 
 
   +----------------+   +----------------+   +----------------+
   |  Symbol Names  |   |  Symbol Count  |   |  D.P. Values   |
   |                |   +----------------+   |  Associated    |
   |                |   |  Value Count   |   |  With Symbols  |
   |                |   +----------------+   |                |
   |                |   |  Name Length   |   |  (possibly     |
   |                |   +----------------+   |   multiple     |
   |                |   |                |   |   values per   |
   |                |   | Value Counts   |   |   symbol)      |
   |                |   | For Each Symbol|   |                |
   |                |   |                |   |                |
   |                |   |                |   |                |
   |                |   |                |   |                |
   |                |   +----------------+   |                |
   |                |                        |                |
   +----------------+                        |                |
                                             |                |
                                             |                |
                                             +----------------+
      DAS Character        DAS integer          DAS double precision
      virtual array        virtual array        virtual array
 
</PRE>
   The source code of WRSYMD is shown below:
<P>
 
<PRE>
 
 
         SUBROUTINE WRSYMD ( HANDLE, SYMNAM, SYMPTR, SYMVAL )
   C
   C     Write a double precision symbol table to a DAS file.
   C
         INTEGER               LBCELL
         PARAMETER           ( LBCELL = - 5)
 
         INTEGER               HANDLE
         CHARACTER*(*)         SYMNAM ( LBCELL : * )
         INTEGER               SYMPTR ( LBCELL : * )
         DOUBLE PRECISION      SYMVAL ( LBCELL : * )
 
   C$ Brief_I/O
   C
   C     VARIABLE  I/O  DESCRIPTION
   C     --------  ---  ----------------------------------------------
   C     HANDLE     I   Handle of DAS file opened for writing.
   C     TABSYM,
   C     TABPTR,
   C     TABVAL     I   Components of the symbol table.
   C
 
   C
   C     SPICELIB functions
   C
         INTEGER               CARDC
         INTEGER               CARDD
         LOGICAL               RETURN
 
   C
   C     Local parameters
   C
         INTEGER               MAXVAL
         PARAMETER           ( MAXVAL = 5000 )
 
   C
   C     Local variables
   C
         DOUBLE PRECISION      VALUES ( MAXVAL )
 
         INTEGER               FIRST
         INTEGER               I
         INTEGER               LAST
         INTEGER               N
         INTEGER               NAMLEN
         INTEGER               NSYM
         INTEGER               NVAL
 
         LOGICAL               FOUND
 
   C
   C     Standard SPICELIB error handling.
   C
         IF ( RETURN() ) THEN
            RETURN
         ELSE
            CALL CHKIN ( 'WRSYMD' )
         END IF
 
   C
   C     Write the symbol and symbol value counts to the file.  Also
   C     write out the length of the symbol name strings, so a reader
   C     program can know how many characters to read to obtain each
   C     name.
   C
         NSYM    =  CARDC (SYMNAM)
         NVAL    =  CARDD (SYMVAL)
         NAMLEN  =  LEN ( SYMNAM(1) )
 
         CALL DASADI ( HANDLE, 1, NSYM,   FIRST, LAST )
         CALL DASADI ( HANDLE, 1, NVAL,   FIRST, LAST )
         CALL DASADI ( HANDLE, 1, NAMLEN, FIRST, LAST )
 
   C
   C     Now write out the symbol table entries.  For each symbol,
   C     we'll append the symbol's name to the DAS's virtual character
   C     array, the value count to the virtual integer array, and the
   C     values to the virtual double precision array.
   C
         DO I = 1, NSYM
   C
   C        Look up the values associated with each symbol.  We don't
   C        need to check the FOUND flag because we already know the
   C        symbols exist.
   C
            CALL SYGETD ( SYMNAM(I),
        .                 SYMNAM,    SYMPTR,    SYMVAL,
        .                 N,         VALUES,    FOUND   )
 
   C
   C        Add the symbol's name to the DAS file.
   C
            CALL DASADC ( HANDLE,  1,  SYMNAM(I),  FIRST,  LAST )
 
   C
   C        Now the value count.
   C
            CALL DASADI ( HANDLE,  1,  N,          FIRST,  LAST )
 
   C
   C        Finally, the values themselves.
   C
            CALL DASADD ( HANDLE,  N,  VALUES,     FIRST,  LAST )
 
         END DO
 
 
         CALL CHKOUT ( 'WRSYMD' )
         RETURN
         END
 
 
 
 
</PRE>
   The symbol table placed in a DAS file by WRSYMD may be extracted by
   RDSYMD, shown below:
<P>
 
<PRE>
 
 
 
         SUBROUTINE RDSYMD ( HANDLE, SYMNAM, SYMPTR, SYMVAL )
   C
   C     Read a double precision symbol table from a DAS file.
   C
         INTEGER               LBCELL
         PARAMETER           ( LBCELL = - 5)
 
         INTEGER               HANDLE
         CHARACTER*(*)         SYMNAM ( LBCELL : * )
         INTEGER               SYMPTR ( LBCELL : * )
         DOUBLE PRECISION      SYMVAL ( LBCELL : * )
 
   C$ Brief_I/O
   C
   C     VARIABLE  I/O  DESCRIPTION
   C     --------  ---  ----------------------------------------------
   C     HANDLE     I   Handle of DAS file opened for writing.
   C     TABSYM,
   C     TABPTR,
   C     TABVAL     O   Components of the symbol table.  These cells
   C                    are presumed to be initialized on input.
   C
 
   C
   C     SPICELIB functions
   C
         LOGICAL               RETURN
 
   C
   C     Local parameters
   C
         INTEGER               CHAR
         PARAMETER           ( CHAR   = 1 )
 
         INTEGER               DP
         PARAMETER           ( DP     = 2 )
 
         INTEGER               INT
         PARAMETER           ( INT    = 3 )
 
         INTEGER               MAXVAL
         PARAMETER           ( MAXVAL = 5000 )
 
         INTEGER               MAXLEN
         PARAMETER           ( MAXLEN =   80 )
 
   C
   C     Local variables
   C
         CHARACTER*(MAXLEN)    VARNAM
 
         DOUBLE PRECISION      VALUES ( MAXVAL )
 
         INTEGER               FIRST ( 3 )
         INTEGER               I
         INTEGER               L
         INTEGER               LAST  ( 3 )
         INTEGER               N
         INTEGER               NAMLEN
         INTEGER               NSYM
         INTEGER               NVAL
 
   C
   C     Standard SPICELIB error handling.
   C
         IF ( RETURN() ) THEN
            RETURN
         ELSE
            CALL CHKIN ( 'RDSYMD' )
         END IF
 
   C
   C     Read the symbol and symbol value counts from the file.  Also
   C     get the length of the symbol name strings.
   C
         CALL DASRDI ( HANDLE, 1, 1, NSYM   )
         CALL DASRDI ( HANDLE, 2, 2, NVAL   )
         CALL DASRDI ( HANDLE, 3, 3, NAMLEN )
 
   C
   C     Now read the symbols, their value counts, and their values.
   C     Add each symbol to the output symbol table.
   C
   C     Obtain the length of the names in the symbol table.  Check
   C     that the elements of the input name array are long enough.
   C
         L  =  LEN ( SYMNAM(1) )
 
         IF ( L .LT. NAMLEN ) THEN
 
            CALL SETMSG ( 'Name array has width #; required width ' //
        .                 'is #'                                     )
            CALL ERRINT ( '#',  L                                    )
            CALL ERRINT (  NAMLEN                                    )
            CALL SIGERR ( 'NAMEARRAYTOONARROW'                       )
            CALL CHKOUT ( 'RDSYMD'                                   )
            RETURN
 
         END IF
 
   C
   C     Initialize our logical address ranges.
   C
         CALL CLEARI ( 3, FIRST )
 
         LAST(CHAR) = 0
         LAST(DP)   = 0
         LAST(INT)  = 3
 
 
         DO I = 1, NSYM
   C
   C        Obtain the symbol's name.
   C
            FIRST(CHAR)  =  LAST(CHAR)  +  1
            LAST (CHAR)  =  LAST(CHAR)  +  NAMLEN
 
            CALL DASRDC (  HANDLE,
        .                  FIRST(CHAR),  LAST(CHAR),
        .                  1,            NAMLEN,      VARNAM  )
 
   C
   C        Now obtain the symbol's value count.
   C
            FIRST(INT)   =  LAST(INT)   +  1
            LAST (INT)   =  LAST(INT)   +  1
 
            CALL DASRDI ( HANDLE, FIRST(INT), LAST(INT), N )
 
   C
   C        Now get the symbol's values.
   C
            FIRST(DP)    =  LAST(DP)    +  1
            LAST (DP)    =  LAST(DP)    +  N
 
            CALL DASRDD ( HANDLE, FIRST(DP), LAST(DP), VALUES )
 
   C
   C        Add the symbol to the output symbol table.
   C
            CALL SYPUTD (  VARNAM(1:NAMLEN),  VALUES,  N,
        .                  SYMNAM,            SYMPTR,  SYMVAL  )
 
         END DO
 
 
         CALL CHKOUT ( 'RDSYMD' )
         RETURN
         END
</PRE>

</TD>
</TR>
</TBODY>
</TABLE>

</BODY>

</HTML>
